home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / dev / misc / OpalDev.lha / opal.doc < prev    next >
Text File  |  1992-10-01  |  70KB  |  2,597 lines
  1. TABLE OF CONTENTS
  2.  
  3. opal.library/ActiveScreen24
  4. opal.library/AmigaPriority
  5. opal.library/AppendCopper24
  6. opal.library/AutoSync24
  7. opal.library/BitPlanetoOV
  8. opal.library/ClearDisplayBottom24
  9. opal.library/ClearPFStencil24
  10. opal.library/ClearPRStencil24
  11. opal.library/ClearQuick24
  12. opal.library/ClearScreen24
  13. opal.library/CloseScreen24
  14. opal.library/Config24
  15. opal.library/CreateScreen24
  16. opal.library/DisablePRStencil24
  17. opal.library/DisplayFrame24
  18. opal.library/DisplayThumbnail24
  19. opal.library/DrawEllipse24
  20. opal.library/DrawLine24
  21. opal.library/DualDisplay24
  22. opal.library/DualPlayField2
  23. opal.library/EnablePRStencil24
  24. opal.library/FadeIn24
  25. opal.library/FadeOut24
  26. opal.library/FreeScreen24
  27. opal.library/FreezeFrame24
  28. opal.library/ILBMtoOV
  29. opal.library/LatchDisplay24
  30. opal.library/LoadImage24
  31. opal.library/LowMemUpdate24
  32. opal.library/LowMem2Update24
  33. opal.library/LowMemRGB24
  34. opal.library/OpenScreen24
  35. opal.library/OVPriority
  36. opal.library/OVtoBitPlane
  37. opal.library/OVtoILBM
  38. opal.library/OVtoRGB
  39. opal.library/PaletteMap24
  40. opal.library/ReadPFPixel24
  41. opal.library/ReadPixel24
  42. opal.library/ReadPRPixel24
  43. opal.library/RectFill24
  44. opal.library/Refresh24
  45. opal.library/RegWait24
  46. opal.library/RGBtoOV
  47. opal.library/SaveIFF24
  48. opal.library/SaveJPEG24
  49. opal.library/Scroll24
  50. opal.library/SetControlBit24
  51. opal.library/SetCoPro24
  52. opal.library/SetDisplayBottom24
  53. opal.library/SetHires24
  54. opal.library/SetLoadAddress24
  55. opal.library/SetLores24
  56. opal.library/SetPFStencil24
  57. opal.library/SetPRStencil24
  58. opal.library/SetRGB24
  59. opal.library/SetScreen24
  60. opal.library/SetSprite24
  61. opal.library/SingleDisplay24
  62. opal.library/SinglePlayField24
  63. opal.library/StopUpdate24
  64. opal.library/UpdateAll24
  65. opal.library/UpdateCoPro24
  66. opal.library/UpdateDelay24
  67. opal.library/UpdatePalette24
  68. opal.library/UpdatePFStencil24
  69. opal.library/UpdateRegs24()
  70. opal.library/WriteFrame24
  71. opal.library/WritePFPixel24
  72. opal.library/WritePixel24
  73. opal.library/WritePRPixel24
  74. opal.library/WriteThumbnail24
  75.  
  76. opalreq.library/OpalRequester
  77.  
  78.  
  79. opal.library/ActiveScreen24
  80.  
  81.     NAME
  82.     ActiveScreen24 -- Provides a pointer to the currently displayed OpalVision screen.
  83.  
  84.     SYNOPSIS
  85.     OScrn = ActiveScreen24 (void);
  86.     D0
  87.  
  88.     struct OpalScreen *OScrn;
  89.  
  90.     FUNCTION
  91.     This function provides a pointer to the currently displayed OpalVision screen. If there is no OpalVision 
  92.     display active then a null value is returned.
  93.  
  94.     This call is useful for writing background colour cycling or coprocessor effects programs to affect the 
  95.     currently open screen. 
  96.  
  97.     INPUTS
  98.     None
  99.  
  100.     RESULT
  101.     OScrn    -A pointer to the currently open OpalVision screen, or NULL.
  102.  
  103.     CONSIDERATIONS
  104.  
  105.     Caution must be exercised when dealing with screens owned by another task. Bitplane access should be 
  106.     avoided unless running cooperative tasks with mutually exclusive bitplane access.
  107.  
  108.     SEE ALSO
  109.  
  110.     OpenScreen24()
  111.  
  112. opal.library/AmigaPriority
  113.  
  114.     NAME
  115.     AmigaPriority -- Gives Amiga graphics priority over OpalVision display.
  116.  
  117.     SYNOPSIS
  118.     void AmigaPriority (void);
  119.  
  120.     FUNCTION
  121.     This function clears the OVPRI bit of all CoPro instructions which gives Amiga graphics priority over 
  122.     OpalVision graphics. If a dual display has not been set, only Amiga graphics will be visible.
  123.  
  124.     INPUTS
  125.     None
  126.  
  127.     RESULT
  128.     None
  129.  
  130.     CONSIDERATIONS
  131.     If an Opal display bottom has been set, the coprocessor instructions will not be 
  132.     modified for that region of the display.
  133.  
  134.     SEE ALSO
  135.     OVPriority()
  136.     DualDisplay24()
  137. opal.library/AppendCopper24
  138.  
  139.     NAME
  140.     AppendCopper24 -- Attaches user copper lists to existing display copper lists.
  141.  
  142.     SYNOPSIS
  143.     void AppendCopper24 (CopLists);
  144.                 A0
  145.  
  146.     UWORD **CopLists[12];
  147.  
  148.     FUNCTION
  149.     Up to 12 different Amiga copper lists are used to update the OpalVision memory. This function allows 
  150.     user copper lists to be attached to the end of each of the lists to enable split screen 24bit displays and 
  151.     other copper effects. 
  152.  
  153.     Each copper list must be terminated with $FFFFFFFE followed by 30 free bytes for linkage code.
  154.  
  155.     After attaching copper lists, the LastWait field in the OpalScreen structure must be initialised with the 
  156.     last vertical position wait in the attached copper lists.
  157.  
  158.     The VStart field in the OpalScreen structure contains the scan line of the first displayed line for the 
  159.     screen. To convert a display 'y' coordinate to a vertical copper wait instruction, use VWait = y + VStart.
  160.  
  161.     INPUTS
  162.     CopLists    - Pointer to an array of 12 copper list pointers to be joined to the current display copper lists.
  163.  
  164.     RESULT
  165.     None
  166.  
  167.     CONSIDERATIONS
  168.     All copper lists must reside in chip ram.
  169.  
  170.     SEE ALSO
  171.  
  172. opal.library/AutoSync24
  173.  
  174.     NAME
  175.     AutoSync24 -- Enables auto horizontal synchronisation.
  176.  
  177.     SYNOPSIS
  178.     void  AutoSync24 (Sync);
  179.               D0
  180.  
  181.     BOOL Sync;
  182.  
  183.     FUNCTION
  184.     Enables the OpalVision's auto synchronisation mode (see "Horizontal Synchronisation").  This mode will 
  185.     be automatically disabled when frame buffer updates are occurring, and re-enabled when they cease.
  186.  
  187.     INPUTS
  188.     Sync =    0 = Disable auto syncing,  1 = Enable auto syncing.
  189.  
  190.     RESULT
  191.     None
  192.  
  193.     CONSIDERATIONS
  194.  
  195.     SEE ALSO
  196.  
  197.  
  198. opal.library/BitPlanetoOV
  199.  
  200.     NAME
  201.     BitPlanetoOV -- Converts standard bitplane data to OpalVision format.
  202.  
  203.     SYNOPSIS
  204.     void BitPlanetoOV (OScrn, SrcPlanes, SrcWidth, Lines, TopLine, SrcDepth)
  205.                A0      A1         D0           D1     D2       D3
  206.  
  207.     struct OpalScreen *OScrn;
  208.     UBYTE **SrcPlanes[];
  209.     long SrcWidth;
  210.     long Lines;
  211.     long TopLine;
  212.     long SrcDepth;
  213.  
  214.     FUNCTION
  215.  
  216.     Converts bit plane data from the supplied bitplanes into OpalVision memory format and stores this in the 
  217.     OpalScreen supplied.
  218.  
  219.     The source data will be clipped if it is wider than the destination screen, or will be padded out if it is 
  220.     narrower.
  221.  
  222.     INPUTS
  223.     OScrn     = Destination OpalScreen.
  224.     SrcPlanes     = A pointer to an array of pointers to source Bitplanes.
  225.     SrcWidth    = Byte width of source planes (must be even).
  226.     Lines     = Number of lines to convert.
  227.     TopLine     = Starting line to place destination data.
  228.     SrcDepth    = The number of bitplanes in SrcPlanes.
  229.  
  230.     RESULT
  231.     None
  232.  
  233.     CONSIDERATIONS
  234.     All bitplanes must start on a word boundary, and SrcWidth must be even.
  235.  
  236.     SEE ALSO
  237.     OVtoBitPlane()
  238.  
  239. opal.library/ClearDisplayBottom24
  240.  
  241.     NAME
  242.     ClearDisplayBottom24 -- Clears the OpalVision display bottom setting.
  243.  
  244.     SYNOPSIS
  245.     void ClearDisplayBottom24 (void)
  246.  
  247.     FUNCTION
  248.     Remove the OpalVision display bottom previously set with a call to SetDisplayBottom24().
  249.  
  250.     INPUTS
  251.     None
  252.  
  253.     RESULT
  254.     None
  255.  
  256.     CONSIDERATIONS
  257.  
  258.  
  259.     SEE ALSO
  260.     SetDisplayBottom24()
  261.  
  262. opal.library/ClearPFStencil24
  263.  
  264.     NAME
  265.     ClearPFStencil24 -- Clears the PlayField Stencil of the specified screen.
  266.  
  267.     SYNOPSIS
  268.     void ClearPFStencil24 (OScrn);
  269.                 A0
  270.  
  271.     struct OpalScreen *OScrn;
  272.  
  273.     FUNCTION
  274.     Clears the playfield stencil (least significant bit of green bank 0) of all of the pixels in the specified 
  275.     screen.
  276.  
  277.     INPUTS
  278.     OScrn    = OpalScreen structure.
  279.  
  280.     RESULT
  281.     None
  282.  
  283.     CONSIDERATIONS
  284.     This will only have a visible effect if Dual Playfield mode has been set up using DualPlayField24().
  285.  
  286.     SEE ALSO
  287.     SetPFStencil24()
  288.     DualPlayField24()
  289.     SinglePlayField24()
  290.  
  291. opal.library/ClearPRStencil24
  292.  
  293.     NAME
  294.     ClearPRStencil24 -- Clears the Priority Stencil of the specified Screen.
  295.  
  296.     SYNOPSIS
  297.     void ClearPRStencil24 (OScrn);
  298.                 A0
  299.  
  300.     struct OpalScreen *OScrn;
  301.  
  302.     FUNCTION
  303.     Clears the priority stencil (least significant bit of blue bank 0) of the all of the pixels in the specified 
  304.     screen.
  305.  
  306.     INPUTS
  307.     OScrn    = OpalScreen structure.
  308.  
  309.     RESULT
  310.     None
  311.  
  312.     CONSIDERATIONS
  313.     This will only have a visible effect if dual OpalVision/Amiga display mode has been set up using 
  314.     DualDisplay24().
  315.  
  316.     SEE ALSO
  317.     SetPRStencil24()
  318.     DualDisplay24()
  319.     SingleDisplay24()
  320.  
  321. opal.library/ClearQuick24
  322.  
  323.     NAME
  324.     ClearQuick24 -- Clears OpalVision frame buffer memory.
  325.  
  326.     SYNOPSIS
  327.     void ClearQuick24 (void)
  328.  
  329.     FUNCTION
  330.     This function clears the frame buffer memory as quickly as possible by enabling a write to all banks of 
  331.     memory. This function will also zero all bitplanes in memory (see ClearScreen24()). This operation will 
  332.     take 1 frame to clear any resolution non-interlaced display, and 2 frames for an interlaced display.This 
  333.     function  acts on the current display screen and cannot be used for virtual screens.
  334.  
  335.     This function is called by OpenScreen24.
  336.  
  337.     INPUTS
  338.     None
  339.  
  340.     RESULT
  341.     None
  342.  
  343.     CONSIDERATIONS
  344.  
  345.  
  346.     SEE ALSO
  347.     ClearScreen24()
  348.  
  349. opal.library/ClearScreen24
  350.  
  351.     NAME
  352.     ClearScreen24 -- Clears all bitplanes in a screen.
  353.  
  354.  
  355.     SYNOPSIS
  356.     void ClearScreen24 (OScrn)
  357.                 A0
  358.  
  359.     struct OpalScreen *OScrn;
  360.  
  361.     FUNCTION
  362.     Clear all bitplanes contained in the OpalScreen structure which may be a virtual screen or the display 
  363.     screen.
  364.  
  365.     This function clears the bitplane memory without updating the frame buffer (unless frame buffer updates 
  366.     are enabled).
  367.  
  368.     INPUTS
  369.     OScrn = Pointer to the Opal screen to be cleared.
  370.  
  371.     RESULT
  372.     None
  373.  
  374.     CONSIDERATIONS
  375.  
  376.  
  377.     SEE ALSO
  378.     ClearQuick24()
  379. opal.library/CloseScreen24
  380.  
  381.     NAME
  382.     CloseScreen24 -- Stop current display and free resources.
  383.  
  384.     SYNOPSIS
  385.     void CloseScreen24 (void);
  386.  
  387.     FUNCTION
  388.     This function closes the current displayed screen if it was opened by the current task.
  389.  
  390.     A screen opened by another task can be closed if it was opened with the CLOSEABLE24 flag. Backdrop 
  391.     and other low priority programs should use the following procedure to open screen.
  392.  
  393.         OScrn = OpenScreen24 (CLOSEABLE24);
  394.             .
  395.             .
  396.             .
  397.             .
  398.         if (OScrn!=NULL)
  399.             { WaitPort (OScrn->UserPort);
  400.                CloseScreen24();
  401.                Mesg = GetMsg (OScrn->UserPort);
  402.                ReplyMsg (Mesg);
  403.             }
  404.  
  405.     The task will be sent a message when another task is trying to open a screen or close down the one 
  406.     already open. Note that the screen MUST be closed before replying to the message.
  407.  
  408.     An alternative method to create a backdrop is to update the frame buffer, latch the 24 bit display using 
  409.     LatchDisplay24() and then call CloseScreen24(). The contents of the frame buffer will remain visible 
  410.     until another task calls OpenScreen24().
  411.  
  412.     INPUTS
  413.     None
  414.  
  415.     RESULT
  416.     None
  417.  
  418.     CONSIDERATIONS
  419.  
  420.     SEE ALSO
  421.  
  422.     OpenScreen24()
  423.  
  424. opal.library/Config24
  425.  
  426.     NAME
  427.     Config24 --     Returns the OpalVision hardware configuration.
  428.  
  429.     SYNOPSIS
  430.     Config = Config24 (void);
  431.     D0
  432.  
  433.     long Config;
  434.  
  435.     FUNCTION
  436.     Returns flags indicating the hardware configuration of the 24bit display card, future flags  will give 
  437.     details on the existence of OpalVision modules such as the Video Roaster Chip and the frame grabber 
  438.     genlock module.
  439.  
  440.     Current return flags are:
  441.  
  442.         OVCF_OPALVISION    - Display board is an OpalVision card.
  443.         OVCF_COLORBURST    - Display board is a ColorBurst.
  444.  
  445.     INPUTS
  446.  
  447.  
  448.     RESULT
  449.  
  450.  
  451.     CONSIDERATIONS
  452.  
  453.  
  454.     SEE ALSO
  455.  
  456.  
  457. opal.library/CreateScreen24
  458.  
  459.     NAME
  460.     CreateScreen24 -- Creates an arbitrarily sized virtual OpalScreen.
  461.  
  462.     SYNOPSIS
  463.     OScrn = CreateScreen24 (ScreenModes,Width,Height)
  464.                 D0        D1    D2
  465.  
  466.     struct OpalScreen *OScrn;
  467.     long Width;
  468.     long Height;
  469.     long ScreenModes;
  470.  
  471.     FUNCTION
  472.     This function can create an arbitrarily sized OpalScreen in Fast Ram. The bitplanes for the screen are 
  473.     allocated and an OpalScreen structure initialised, this is the virtual screen equivalent of OpenScreen24().
  474.  
  475.     Once this screen has been opened, all drawing, file and Memory conversion functions can be applied to 
  476.     this screen, however it cannot be directly displayed. This allows large super bitmap screens to be 
  477.     allocated in fast ram for manipulation, or to be partially copied to a primary OpalScreen in chip ram for 
  478.     display (to allow for scrolling).
  479.  
  480.     NOTE: Virtual screens are now  displayable using the LowMemUpdate() function, virtual screens are 
  481.     therefore recommended when doing one off frame buffer updates (such as the Show24 command) as it 
  482.     significantly reduces the chip ram requirements 
  483.  
  484.     INPUTS
  485.     Width          = Width in pixels of the screen to be opened.
  486.     Height          = Height in pixels of the screen to be opened.
  487.     ScreenModes = ScreenModes are identical to those of OpenScreen24().
  488.  
  489.     RESULT
  490.     OScrn    = Is a pointer to the new OpalScreen structure or NULL if there is insufficient memory     
  491.         to open the screen size specified.
  492.  
  493.     CONSIDERATIONS
  494.     This function allocates memory with no MEMF_ bits set, the program FastMemFirst should be executed 
  495.     to force all planes to be loaded into fast ram, under AmigaDOS 1.3 or previous.
  496.  
  497.     SEE ALSO
  498.     FreeScreen24()
  499.     OpenScreeen24()
  500.  
  501. opal.library/DisablePRStencil24
  502.  
  503.     NAME
  504.     DisablePRStencil24 -- Disables the use of the priority stencil in dual display mode. 
  505.  
  506.     SYNOPSIS
  507.     void DisablePRStencil24 (void);
  508.  
  509.     FUNCTION
  510.     This function clears the PRISTENCIL bit of all CoPro instructions.
  511.  
  512.     INPUTS
  513.     None
  514.  
  515.     RESULT
  516.     None
  517.  
  518.     CONSIDERATIONS
  519.     If an Amiga display bottom has been set using SetDisplayBottom24(), the CoPro instructions will not be 
  520.     modified for that part of the display.
  521.  
  522.     The priority stencil will only have an effect when a Dual Display is enabled by calling DualDisplay24().
  523.  
  524.     SEE ALSO
  525.     EnablePRStencil()
  526.     DualDisplay24()
  527.     SingleDisplay24()
  528.  
  529. opal.library/DisplayFrame24
  530.  
  531.     NAME
  532.     DisplayFrame24 -- Sets the currently displayed frame within the frame buffer memory.
  533.  
  534.     SYNOPSIS
  535.     void DisplayFrame24 (Frame);
  536.                  D0
  537.  
  538.     long Frame;
  539.  
  540.     FUNCTION
  541.     Depending on the resolution of the displayed OpalVision screen, a number of screens can be stored in the 
  542.     frame buffer memory. The number of frames available for the screens resolution are given in the 
  543.     MaxFrames field in the OpalScreen structure.
  544.  
  545.     DisplayFrame24() allows each individual frame to be displayed separately where Frame is in the range 
  546.     0...MaxFrames. Using a combination of WriteFrame24 and DisplayFrame24, it is possible to store 
  547.     several images in frame buffer memory and to perform simple page flip animation.  
  548.  
  549.     INPUTS
  550.     Frame    = Frame number to display (0...MaxFrames).
  551.  
  552.     RESULT
  553.     None
  554.  
  555.     CONSIDERATIONS
  556.     The display frame and the write frame, must reside in the same field area in the frame buffer memory. 
  557.     (See "Memory Segment Diagram"). Due to this DisplayFrame24() has the side effect of changing the 
  558.     write frame if the new display frame is in a different field. 
  559.  
  560.     SEE ALSO
  561.     WriteFrame24()
  562.  
  563. opal.library/DisplayThumbnail24
  564.  
  565.     NAME
  566.     DisplayThumbnail24 -- Displays a file's thumbnail.
  567.  
  568.     SYNOPSIS
  569.     ReturnCode = DisplayThumbnail24 (OScrn, FileName, x, y);
  570.     D0                 A0     A1      D0 D1
  571.  
  572.     long ReturnCode;
  573.     struct OpalScreen *OScrn;
  574.     char *FileName;
  575.     long x;
  576.     long y;
  577.  
  578.     FUNCTION
  579.     This function displays the imbedded thumbnail in the file described by FileName if it exists.
  580.  
  581.     The x coordinate is rounded down to the nearest multiple of four in low resolution mode and to the 
  582.     nearest multiple of 8 in high resolution mode. The y coordinate is rounded down to the nearest even line 
  583.     in interlaced mode.
  584.  
  585.     INPUTS
  586.  
  587.     OScrn    = Pointer to an OpalScreen structure.
  588.     FileName= The file name of the picture file with the thumbnail.
  589.     x    = The x coordinate of the  screen position to display the thumbnail.
  590.     y    = The y coordinate of the screen position to display the thumbnail. 
  591.  
  592.     RESULT
  593.     ReturnCode    = OL_ERR Codes described in Opallib.h.                    
  594.     OL_ERR_NOTHUMBNAIL is returned if no thumbnail exists in the file.
  595.  
  596.     CONSIDERATIONS
  597.     Thumbnails must always be displayed in low resolution non interlaced mode. For an example of 
  598.     displaying thumbnails in a high resolution and interlaced screen, see the example program 
  599.     "DisplayDir.c"
  600.  
  601.     SEE ALSO
  602.     WriteThumbnail24()
  603.     SaveIFF24()
  604.  
  605. opal.library/DrawEllipse24
  606.  
  607.     NAME
  608.     DrawEllipse24 -- Draw an ellipse of given dimensions.
  609.  
  610.     SYNOPSIS
  611.     void DrawEllipse24 (OScrn,  cx,  cy,  a,  b)
  612.                 A0        D0   D1   D2  D3
  613.  
  614.     struct OpalScreen *OScrn;
  615.     long cx;
  616.     long cy;
  617.     long a;
  618.     long b;
  619.  
  620.     FUNCTION
  621.     Draws an ellipse in the supplied screen.
  622.  
  623.     NOTE: set a=b for circles.
  624.  
  625.     INPUTS
  626.  
  627.     OScrn     = Destination OpalScreen.
  628.     cx     = Centre x-Coordinate of ellipse.
  629.     cy     = Centre y-Coordinate of ellipse.
  630.     a     = horizontal radius of ellipse (must be >0).
  631.     b     = vertical radius of ellipse (must be >0).
  632.  
  633.     RESULT
  634.  
  635.     CONSIDERATIONS
  636.     The ellipse will only be rendered in the region specified by the clip region in the screen structure.
  637.  
  638.     SEE ALSO
  639.  
  640. opal.library/DrawLine24
  641.  
  642.     NAME
  643.     DrawLine24 -- Draws a line into an OpalScreen.
  644.  
  645.     SYNOPSIS
  646.     void DrawLine24 (OScrn, x1, y1, x2, y2)
  647.              A0     D0  D1  D2  D3
  648.  
  649.     struct OpalScreen *OScrn;
  650.     long x1;
  651.     long y1;
  652.     long x2;
  653.     long y2;
  654.  
  655.     FUNCTION
  656.     Draws a line in the specified screen structure which may be a virtual or display screen.
  657.  
  658.     In 24bit mode the colour of the line is specified by the Pen_R, Pen_G and Pen_B fields in the OpalScreen 
  659.     structure. In 15bit mode, Pen_R and Pen_G specify the colour of the line, while in 8bit only Pen_R is 
  660.     used. 
  661.  
  662.     INPUTS
  663.     OScrn    = The OpalScreen structure in which to draw.
  664.     x1, y1    = The starting co-ordinates of the line.
  665.     x2, y2    = The ending co-ordinates of the line.
  666.  
  667.     RESULT
  668.  
  669.  
  670.     CONSIDERATIONS
  671.     The line will only be rendered in the region specified by the clip region in the screen structure.
  672.  
  673.     SEE ALSO
  674.  
  675. opal.library/DualDisplay24
  676.  
  677.     NAME
  678.     DualDisplay24 -- Sets up an Amiga/OpalVision dual display.
  679.  
  680.     SYNOPSIS
  681.     void DualDisplay24 (void);
  682.  
  683.     FUNCTION
  684.     This function clears the DUALDISPLAY bit of all CoPro instructions, enabling a Dual 
  685.     Amiga/OpalVision display. The priority of the Amiga/OpalVision graphics can be set with OVPriority() 
  686.     and AmigaPriority().
  687.  
  688.     INPUTS
  689.     None
  690.  
  691.     RESULT
  692.     None
  693.  
  694.     CONSIDERATIONS
  695.     If an Amiga display bottom has been set, using the SetDisplayBottom24() the CoPro instructions will not 
  696.     be modified for that region of the display.
  697.  
  698.     SEE ALSO
  699.     SingleDisplay24()
  700.     AmigaPriority()
  701.     OVPriority()
  702.  
  703. opal.library/DualPlayField2
  704.  
  705.     NAME
  706.     DualPlayField24 -- Sets up an OpalVision 24bit dual playfield.
  707.  
  708.     SYNOPSIS
  709.     void DualPlayField (void)
  710.  
  711.     FUNCTION
  712.     This function sets the DUALPLAYFIELD bit of all CoPro instructions, allowing a dual 24 bit overlay 
  713.     mode. To determine which bank is displayed for each pixel, the playfield stencil needs to be set 
  714.     accordingly.
  715.  
  716.     INPUTS
  717.     None
  718.  
  719.     RESULT
  720.     None
  721.  
  722.     CONSIDERATIONS
  723.     If an Amiga display bottom has been set using SetDisplayBottom24(), the coprocessor instructions will 
  724.     not be modified for that region of the display.
  725.  
  726.     SEE ALSO
  727.     SinglePlayField24()
  728. opal.library/EnablePRStencil24
  729.  
  730.     NAME
  731.     EnablePRStencil24 -- Enables the use of the priority stencil in dual display mode. 
  732.  
  733.     SYNOPSIS
  734.     void EnablePRStencil24 (void);
  735.  
  736.     FUNCTION
  737.     This function set the PRISTENCIL bit of all CoPro instructions.
  738.  
  739.     INPUTS
  740.     None
  741.  
  742.     RESULT
  743.     None
  744.  
  745.     CONSIDERATIONS
  746.     If an Amiga display bottom has been set using SetDisplayBottom24(), the CoPro instructions will not be 
  747.     modified for that part of the display.
  748.  
  749.     The priority stencil will only have an effect when a Dual Display is enabled by calling DualDisplay24().
  750.  
  751.     SEE ALSO
  752.     DisablePRStencil()
  753.     DualDisplay24()
  754.     SingleDisplay24()
  755.  
  756. opal.library/FadeIn24
  757.  
  758.     NAME
  759.     FadeIn24 -- Fades display in from black.
  760.  
  761.     SYNOPSIS
  762.     void FadeIn24 (Time);
  763.             D0
  764.  
  765.     long Time;
  766.  
  767.     FUNCTION
  768.     Fade the current display from black to true colour. 
  769.  
  770.     The Time parameter specifies the amount of time in 1/100 seconds the fade should take and is 
  771.     independent of PAL or NTSC refresh rates.
  772.  
  773.     INPUTS
  774.     Time = Time in 1/100 seconds to complete fade.
  775.  
  776.     RESULT
  777.     None
  778.  
  779.     CONSIDERATIONS
  780.     This function cannot be used in 15bit mode.
  781.  
  782.     SEE ALSO
  783.     FadeOut24()
  784. opal.library/FadeOut24
  785.  
  786.     NAME
  787.     FadeOut24 -- Fade display to black.
  788.  
  789.     SYNOPSIS
  790.     void FadeOut24 (Time)
  791.             D0
  792.     long Time;
  793.  
  794.     FUNCTION
  795.     Fade the current display from true colour to black. 
  796.  
  797.     The Time parameter specifies the amount of time the fade should take and is independent of PAL or 
  798.     NTSC machines.
  799.  
  800.     INPUTS
  801.     Time = Number of 1/100ths seconds in which to complete the fade.
  802.  
  803.     RESULT
  804.     None
  805.  
  806.     CONSIDERATIONS
  807.     This function cannot be used in 15bit mode.
  808.  
  809.     SEE ALSO
  810.     FadeIn24()
  811. opal.library/FreeScreen24
  812.  
  813.     NAME
  814.     FreeScreen24 -- Frees a virtual OpalScreen.
  815.  
  816.     SYNOPSIS
  817.     void FreeScreen24 (OScrn); 
  818.                A0
  819.  
  820.     struct OpalScreen *OScrn;
  821.  
  822.     FUNCTION
  823.     This function deallocates all memory associated with a virtual screen. This is the virtual screen 
  824.     equivalent of CloseScreen24. 
  825.  
  826.     INPUTS
  827.     OScrn    = A pointer to the virtual screen to be freed
  828.  
  829.     RESULT
  830.     None
  831.  
  832.     CONSIDERATIONS
  833.  
  834.  
  835.     SEE ALSO
  836.     CreateScreen24()
  837.     CloseScreen24()
  838.  
  839. opal.library/FreezeFrame24
  840.  
  841.     NAME
  842.     FreezeFrame24 -- Freezes the currently displayed screen.
  843.  
  844.     SYNOPSIS
  845.     void FreezeFrame24 (Freeze);
  846.                 D0
  847.     BOOL Freeze
  848.  
  849.     FUNCTION
  850.     This function freezes the current display. If freeze is TRUE, the display is held static. The display is 
  851.     returned to normal when the value for freeze is FALSE.
  852.  
  853.     Freeze freezes everything on the display including Amiga graphics.
  854.  
  855.     INPUTS
  856.     Freeze    = TRUE (1) = Freeze, FALSE (0) = Unfreeze
  857.  
  858.     RESULT
  859.     None
  860.  
  861.     CONSIDERATIONS
  862.     This functions is available only while a Scan Rate Converter is present.
  863.  
  864.     SEE ALSO
  865.  
  866. opal.library/ILBMtoOV
  867.  
  868.     NAME
  869.     ILBMtoOV -- Converts interleaved bitmap to OpalVision format.
  870.  
  871.     SYNOPSIS
  872.     void ILBMtoOV (OScrn, ILBMData, SrcWidth, Lines, TopLine, SrcPlanes)
  873.             A0    A1        D0        D1     D2       D3
  874.  
  875.     struct OpalScreen *OScrn;
  876.     UBYTE *ILBMData;
  877.     long SrcWidth;
  878.     long Lines;
  879.     long TopLine;
  880.     long SrcPlanes;
  881.  
  882.     FUNCTION
  883.     Converts interleaved bitmap memory into OpalVision memory format and stores this in the OpalScreen 
  884.     supplied.
  885.  
  886.     The source data will be clipped if it is wider than the destination screen, or will be padded out if it is 
  887.     narrower.
  888.  
  889.     This function is provided to simplify the task of writing a custom IFF loader.
  890.  
  891.     INPUTS
  892.     OScrn         = Destination OpalScreen.
  893.     ILBMData     = interleaved planes of source data.
  894.     SourceWidth     = Width of source ILBM data.
  895.     Lines         = Number of lines to convert.
  896.     TopLine     = Starting line to place destination data.
  897.     SrcPlanes    =The number of planes contained in the ILBM data.
  898.  
  899.     RESULT
  900.     None
  901.  
  902.     CONSIDERATIONS
  903.  
  904.  
  905.     SEE ALSO
  906.     OVtoILBM()
  907.  
  908. opal.library/LatchDisplay24
  909.  
  910.     NAME
  911.     LatchDisplay24 -- Locks OpalVision  display
  912.  
  913.     SYNOPSIS
  914.     void LatchDisplay24 (Latch)
  915.  
  916.     BOOL Latch;
  917.  
  918.     FUNCTION
  919.     LatchDisplay24 sets or clears the Latch bit in the control line register. If this bit is set,  the OpalVision 
  920.     display will remain active regardless of whether there is a valid control line in the Amigas' output. If 
  921.     CloseScreen24() is called after the latch bit is set, all memory and resources will be freed but the display 
  922.     will still be active, even if the Amiga is reset.
  923.  
  924.     OpalHotKey uses this technique, images are loaded and updated into the buffer, latched and then the 
  925.     screen is closed. If any register information needs to be changed, such as changing display priority a 
  926.     display screen is opened using the CONTROLONLY24 flag which enables registers to be changed 
  927.     without effecting the contents of the frame buffer.
  928.  
  929.     INPUTS
  930.     Latch    = 0 = Free display, 1 = Latch display.
  931.  
  932.     RESULT
  933.     None
  934.  
  935.     CONSIDERATIONS
  936.  
  937.  
  938.     SEE ALSO
  939.  
  940. opal.library/LoadImage24
  941.  
  942.     NAME
  943.     LoadImage24 / LoadIFF24 -- Loads an Image file.
  944.  
  945.     SYNOPSIS
  946.     ReturnCode = LoadImage24 (OScrn,FileName,Flags)
  947.     D0              A0    A1     D0
  948.  
  949.     long ReturnCode;
  950.     struct OpalScreen *OScrn;
  951.     long Flags;
  952.     char *FileName;
  953.  
  954.     FUNCTION
  955.     Load an IFF or JPEG file.
  956.  
  957.     This is a general purpose image loading routine which will automatically detect and load IFF and JPEG 
  958.     files. As this is a general loader, the name of this function has been renamed to LoadImage24(), which is 
  959.     used as a synonym for the previous function name LoadIFF24() to maintain backward compatibility.
  960.  
  961.     The IFF portion of this loader will load IFF 24bit, Fast Format 24 bit, Palette mapped (up to 256 colours), 
  962.     Hold and Modify and Extra half brite files.
  963.  
  964.     All palette mapped files will be loaded in the 8 bit palette mapped mode unless the CONVERT24 flag is 
  965.     set, in which case they will be converted to a non palette mapped 24 bit display.
  966.  
  967.     There are several different forms in which LoadImage24 can load an image. The way in which it 
  968.     functions is dependant on the specified screen and the flags. If the screen pointer is NULL then 
  969.     LoadImage24 will open a screen itself, the screen it opens will be a display screen unless 
  970.     VIRTUALSCREEN24 is set in which case a virtual screen will be created.
  971.  
  972.     If the passed screen structure is not NULL and the image being loaded is the same resolution, then it will 
  973.     be loaded into that screen. If this is not the case then the screen will be closed and a new screen of the 
  974.     same resolution as the file will be opened. However if KEEPRES24 is set, the file will be loaded into the 
  975.     supplied screen regardless of its resolution. 
  976.  
  977.     LoadImage24 returns one of two things. If the files was loaded successfully, a pointer to the screen into 
  978.     which it was loaded is returned. If an error occurred, then an error code will be returned. To determine 
  979.     which of these messages has been returned, the value can be compared to OL_ERR_MAXERR, if it is 
  980.     lower than this value then the result is an error code, if it is greater than this number then it is a screen 
  981.     pointer. If the image is not IFF or JPEG, OL_ERR_FORMATUNKOWN is returned. 
  982.  
  983.     Flags:
  984.         FORCE24        -  Convert palette mapped files to 24 bit.
  985.         KEEPRES24         -  Keep the same screen resolution.
  986.         CLOSEABLE24         -  Opened screen will be closeable.
  987.         LOADMASK24        -  Load mask plane if present (IFF only).
  988.         VIRTUALSCREEN24    -  Load image into a virtual screen.
  989.  
  990.     The JPEG loader is a baseline loader as specified in the draft standard ISO/IEC Bis 10918-1 it supports 
  991.     only 8 bit quantization tables and Huffman entropy compression. It can load files with source colour 
  992.     space of Y Cb Cr, RGB and Grey scale. It does not support non interleaved files, progressive, hierarchical 
  993.     or lossless modes.
  994.  
  995.     INPUTS
  996.     FileName     = Filename of image to be display (including path).
  997.     Flags         = see above.
  998.  
  999.     RESULT
  1000.     ReturnCode = > OL_ERR_MAXERR Return code is a pointer to an Opal screen structure.
  1001.     ReturnCode = < OL_ERR_MAXERR, Return code indicates error.
  1002.  
  1003.     CONSIDERATIONS
  1004.     This function only loads an image, it does not update the frame buffer. To do this you must call 
  1005.     Refresh24() or LowMemUpdate24().
  1006.  
  1007.     SEE ALSO
  1008.     SaveIFF24()
  1009.     SaveJPEG24()
  1010.     Refresh24()
  1011.     LowMemUpdate24()
  1012.  
  1013. opal.library/LowMemUpdate24
  1014.  
  1015.     NAME
  1016.     LowMemUpdate24 -- Low chip ram usage OpalVision update.
  1017.  
  1018.     SYNOPSIS
  1019.     RetScrn = LowMemUpdate24 (OScrn, Frame);
  1020.     D0              A0     D0
  1021.  
  1022.     struct OpalScreen *RetScrn;
  1023.     struct OpalScreen *OScrn;
  1024.     long Frame;
  1025.  
  1026.     FUNCTION
  1027.     Updates the frame buffer from a virtual screen. This function can update an entire image of any 
  1028.     resolution while only using a small amount of chip ram. This routine uses an 8bit screen to update each 
  1029.     memory segment separately, the CPU is used to copy the bitplane data from the virtual screen to chip 
  1030.     ram. The 8bit plane display screen opened to perform the update is returned, and should be subsequently 
  1031.     closed.
  1032.  
  1033.     The Frame input sets the first memory segment to be updated, this will normally be 0. This can be set to 
  1034.     6 for example to update a lores screen to bank1  instead of bank0. 
  1035.  
  1036.     NOTE:  OScrn must be a pointer to a virtual screen.
  1037.  
  1038.     INPUTS
  1039.     OScrn    = The virtual OpalScreen to be displayed
  1040.     Frame    = Memory segment to start update (0..11).
  1041.  
  1042.     RESULT
  1043.     RetScrn       >= OL_ERR_MAXERR Return code is a pointer to an Opal screen structure.
  1044.     RetScrn   < OL_ERR_MAXERR, Return code indicates error.
  1045.  
  1046.     CONSIDERATIONS
  1047.  
  1048.     SEE ALSO
  1049.     LowMem2Update24()
  1050.  
  1051. opal.library/LowMem2Update24
  1052.  
  1053.     NAME
  1054.     LowMem2Update24 -- Low chip ram usage OpalVision update.
  1055.  
  1056.     SYNOPSIS
  1057.     RetScrn = LowMem2Update24 (OScrn, Frame);
  1058.     D0               A0     D0
  1059.  
  1060.     struct OpalScreen *RetScrn;
  1061.     struct OpalScreen *OScrn;
  1062.     long Frame;
  1063.  
  1064.     FUNCTION
  1065.     Updates the frame buffer from a virtual screen. This function can update an entire image of any 
  1066.     resolution while only using a small amount of chip ram. This routine uses an 8bit screen to update each 
  1067.     memory segment separately, the CPU is used to copy the bitplane data from the virtual screen to chip 
  1068.     ram. The 8bit plane display screen opened to perform the update is returned, and should be subsequently 
  1069.     closed.
  1070.  
  1071.     The Frame input sets the first memory segment to be updated, this will normally be 0. This can be set to 
  1072.     6 for example to update a lores screen to bank1  instead of bank0. 
  1073.  
  1074.     This function is similar to LowMemUpdate24() although it only updates the frame buffer memory, it does 
  1075.     not modify the display modes,  CoPro bits or palette information. This is very useful for performing 
  1076.     transitions  between two images in lores, the first image can be written into bank1 and displayed using 
  1077.     LowMemUpdate24(OScrn,6), the second image is then updated transparently into bank0 using 
  1078.     LowMem2Update24(OScrn,0). The dual display stencil can then be used to perform the transition 
  1079.     between bank1 and bank0. Note that bank0 is written to last , as only bank0 contains the dual display 
  1080.     stencil.
  1081.  
  1082.     NOTE:  OScrn must be a pointer to a virtual screen.
  1083.  
  1084.     INPUTS
  1085.     OScrn    = The virtual OpalScreen to be displayed
  1086.     Frame    = Memory segment to start update (0..11).
  1087.  
  1088.     RESULT
  1089.     RetScrn       >= OL_ERR_MAXERR Return code is a pointer to an Opal screen structure.
  1090.     RetScrn   < OL_ERR_MAXERR, Return code indicates error.
  1091.  
  1092.     CONSIDERATIONS
  1093.  
  1094.     SEE ALSO
  1095.     LowMemUpdate24()
  1096.  
  1097. opal.library/LowMemRGB24
  1098.  
  1099.     NAME
  1100.     LowMemRGB24 -- Low chip ram usage OpalVision update from an RGB array.
  1101.  
  1102.     SYNOPSIS
  1103.     RetScrn = LowMemRGB24 (ScreenModes, Frame, Width, Height, Modulo, RGBPlanes);
  1104.     D0            D0        D1       D2      D3      D4      A0
  1105.  
  1106.     struct OpalScreen *RetScrn;
  1107.     long ScreenModes,Frame,Width,Height,Modulo;
  1108.     UBYTE *RGBPlanes[3]
  1109.  
  1110.     FUNCTION
  1111.  
  1112.     Updates the frame buffer from RGB byte planes. This function can update an entire image of any 
  1113.     resolution while only using a small amount of chip ram. This routine uses an 8bit screen to update each 
  1114.     memory segment separately, the RGB data is converted into bitplane format one segment at a time and 
  1115.     transferred into the framebuffer. The 8bit plane display screen opened to perform the update is returned, 
  1116.     and should be subsequently closed.
  1117.  
  1118.     The Modulo parameter allows interleaved RGB data to be updated as well, in this case RGBPlanes would 
  1119.     be initialised 'Width' bytes apart, and modulo would be set to 2*Width.
  1120.  
  1121.     This function is useful for image processing programs such as ADPro and Imagemaster which store 
  1122.     images in byte planes.
  1123.  
  1124.     INPUTS
  1125.     ScreenModes    = See OpenScreen24, these flags enable the resolution and format of the     
  1126.                  displayed image to be set.
  1127.     Frame         = The memory segment to start the update, (0..1)
  1128.     Width        = Width of the RGB Array (in pixels).
  1129.     Height        = Height of the RGB Array. 
  1130.     Modulo        = Modulo to be added after each line in the RGB Array.
  1131.     RGBPlanes    = Pointers to the three byte planes required (R,G,B).
  1132.  
  1133.     RESULT
  1134.     RetScrn       >= OL_ERR_MAXERR Return code is a pointer to an Opal screen structure.
  1135.     RetScrn   < OL_ERR_MAXERR, Return code indicates error.
  1136.  
  1137.     CONSIDERATIONS
  1138.  
  1139.     SEE ALSO
  1140.  
  1141. opal.library/OpenScreen24
  1142.  
  1143.     NAME
  1144.     OpenScreen24 -- Allocates all resources and displays an OpalVision screen.
  1145.  
  1146.     SYNOPSIS
  1147.     OScrn = OpenScreen24 (ScreenModes)
  1148.     D0              D0
  1149.  
  1150.     struct OpalScreen *OScrn;
  1151.     long ScreenModes;
  1152.  
  1153.     FUNCTION
  1154.     This function creates a display screen and allocates all the resources required to display the screen. The 
  1155.     Frame buffer memory is cleared and updates are disabled to the frame buffer memory.
  1156.  
  1157.     The screen is positioned according to Amiga preferences, however if the vertical starting position defined 
  1158.     in preferences is too high up, preferences will be modified to set the vertical starting position to the 
  1159.     highest possible, the preferences will be restored when the screen is closed. 
  1160.  
  1161.     The screen will be opened as single playfield, single display mode with OVPriority.
  1162.  
  1163.     If the CONTROLONLY24 flag is set, the screen will be opened without any bitplanes,  this enables the 
  1164.     copro or palette information of a 'latched on'  to be modified without losing the contents of the frame 
  1165.     buffer.
  1166.  
  1167.     ScreenModes:
  1168.         INTERLACE24    - Open an interlaced screen.
  1169.         HIRES24     - Open a Hires screen.
  1170.         OVERSCAN24    - Open an overscan screen.
  1171.         PLANES15    - 15 bit true colour display.
  1172.         PLANES8        - 8 bit true colour/palette mapped display.
  1173.         CLOSEABLE24    - Screen can be closed by another task.
  1174.         PALMAP24    - Open a palette mapped screen.
  1175.         CONTROLONLY24    - Open a bitplaneless screen.
  1176.  
  1177.     Screen Sizes:
  1178.  
  1179.         Hires    Interlaced    Overscan    PAL    NTSC
  1180.         No    No        No        320x256 320x200
  1181.         Yes    No        No        640x256    640x200
  1182.         No    Yes        No        320x512    320x400
  1183.         Yes    Yes        No        640x512    640x400
  1184.  
  1185.     The size of the screen opened will be as specified above unless there is not enough chip ram available, in 
  1186.     which case the maximum amount of lines possible will be displayed. If there is insufficient chip memory, 
  1187.     to hold half of the scan lines, then OpenScreen will be aborted and NULL returned. If the PLANES8 or 
  1188.     PLANES15 flag is not set, a 24 bit screen will be opened.
  1189.  
  1190.     INPUTS
  1191.     ScreenModes    =  See above.
  1192.  
  1193.     RESULT
  1194.     OScrn    =  A pointer to an OpalScreen structure or NULL if unsuccessful.
  1195.  
  1196.     CONSIDERATIONS
  1197.  
  1198.  
  1199.     SEE ALSO
  1200.     CloseScreen24()
  1201.     LatchDisplay24()
  1202.  
  1203. opal.library/OVPriority
  1204.  
  1205.  
  1206.     NAME
  1207.     OVPriority -- Give OpalVision graphics priority over Amiga graphics.
  1208.  
  1209.     SYNOPSIS
  1210.     void OVPriority (void);
  1211.  
  1212.     FUNCTION
  1213.     This function sets the OVPRI bit of all coprocessor instructions which gives OpalVision graphics priority 
  1214.     over Amiga graphics. If a dual display has not been set, only OpalVision graphics will be visible.
  1215.  
  1216.     INPUTS
  1217.     None
  1218.  
  1219.     RESULT
  1220.     None
  1221.  
  1222.     CONSIDERATIONS
  1223.     If an Amiga display bottom has been set using SetDisplayBottom24(), the coprocessor instructions will 
  1224.     not be modified for that region of the display.
  1225.  
  1226.     SEE ALSO
  1227.     AmigaPriority24()
  1228.     DualDisplay24()
  1229.  
  1230. opal.library/OVtoBitPlane
  1231.     
  1232.     NAME
  1233.     OVtoBitPlane -- Convert OpalVision bit plane data to standard bitplanes.
  1234.  
  1235.     SYNOPSIS
  1236.     void OVtoBitPlane (OScrn, BitPlanes, DestWidth, Lines, TopLine) 
  1237.                A0      A1         D0        D1     D2
  1238.  
  1239.     struct OpalScreen *OScrn;
  1240.     UBYTE **BitPlanes[];
  1241.     long DestWidth;
  1242.     long Lines;
  1243.     long TopLine;
  1244.  
  1245.     FUNCTION
  1246.     Converts OpalVision bitplane format to standard bitplane data. The destination data will be non-
  1247.     interleaved 24, 15 or 8 planes depending on the type of display OScrn is. Note that the 15bit display 
  1248.     mode is actually stored internally as 16 bitplanes which in turn causes this function to return 16 planes 
  1249.     instead of 15.
  1250.  
  1251.     DestWidth specifies the width of the destination bitplanes, if the width is less than the source planes, they 
  1252.     will be clipped. If the destination width is larger, the remaining bytes on each scan line will be skipped.
  1253.  
  1254.     The OpalScreen can be any size, and reside in fast or chip ram.
  1255.  
  1256.     The array of bitplane pointers passed to this function must contain 8, 16 or 24 entries depending on the 
  1257.     screen type.
  1258.  
  1259.     INPUTS
  1260.     OScrn         = OpalScreen structure describing source data.
  1261.     BitPlanes    = Array of bitplane pointers to take the destination data.
  1262.     DestWidth    = Width in bytes of destination planes (must be even).
  1263.     Lines         = Total number of scan lines to convert.
  1264.     TopLine     = Starting line for conversion within the OpalScreen.
  1265.  
  1266.     RESULT
  1267.     None
  1268.  
  1269.     CONSIDERATIONS
  1270.     All bitplanes must be on a word boundary and the destination width must be even.
  1271.  
  1272.     SEE ALSO
  1273.     BitplanetoOV()
  1274.  
  1275. opal.library/OVtoILBM
  1276.  
  1277.     NAME
  1278.     OVtoILBM -- Converts OpalVision bit planes to interleaved bitmap format.
  1279.  
  1280.     SYNOPSIS
  1281.     void OVtoILBM (OScrn, ILBMData, DestWidth, Lines, TopLine)
  1282.             A0    A1        D0         D1     D2
  1283.  
  1284.     struct OpalScreen *OScrn;
  1285.     UBYTE *ILBMData;
  1286.     long DestWidth;
  1287.     long Lines;
  1288.     long TopLine;
  1289.  
  1290.     FUNCTION
  1291.     Converts bitplane information from the supplied OpalScreen, starting at the scan line indicated by 
  1292.     TopLine, into interleaved bitmap format.
  1293.  
  1294.     If the source OpalScreen is wider than the destination width, the planes will be clipped. If the OpalScreen 
  1295.     is narrower, the extra bytes on each line will be skipped. The OpalScreen can be any size, and reside in 
  1296.     fast or chip ram.
  1297.  
  1298.     The memory pointed to by ILBMData must be large enough to hold
  1299.     DestWidth * lines * (8 or 16 or 24 depending on screen type) bytes.
  1300.  
  1301.     INPUTS
  1302.     OScrn         = OpalScreen structure describing source data.
  1303.     ILBMData     = Pointer to buffer to hold destination ILBM data.
  1304.     DestWidth    = Width of destination ILBM planes. (must be even)
  1305.     Lines         = Total number of scan lines to convert.
  1306.     TopLine        = Starting line for conversion within the OpalScreen.
  1307.  
  1308.     RESULT
  1309.     None
  1310.  
  1311.     CONSIDERATIONS
  1312.     ILBMData must start on a word boundary, and DestWidth must be even.
  1313.  
  1314.     SEE ALSO
  1315.     ILBMtoOV()
  1316.  
  1317. opal.library/OVtoRGB
  1318.  
  1319.     NAME
  1320.     OVtoRGB -- Converts OpalVision bitplane data to three planes of RGB.
  1321.  
  1322.     SYNOPSIS
  1323.     void OVtoRGB (OScrn, RGBPlanes[], Top, Left, Width, Height)
  1324.               A0     A1           D0   D1    D2     D3
  1325.  
  1326.     struct OpalScreen *OScrn;
  1327.     UBYTE **RGBPlanes[];
  1328.     long Top;
  1329.     long Left;
  1330.     long Width;
  1331.     long Height;
  1332.  
  1333.     FUNCTION
  1334.     This call converts bitplane data from the OpalScreen into three planes, one containing Red, one Blue and 
  1335.     the last Green, each of these has one byte per pixel. This is useful for making 'brush' cut-outs, or for 
  1336.     subsequent scaling of data.
  1337.  
  1338.     This function is more flexible than the other memory conversion routines in that it can convert a 
  1339.     rectangular region of bitplane memory positioned anywhere within the source screen.
  1340.  
  1341.     The OpalScreen can be any size, and reside in fast or chip ram.
  1342.  
  1343.     INPUTS
  1344.     OScrn        = OpalScreen structure containing source bitplanes.
  1345.     RGBPlanes    = Pointer to an array of 3 plane pointers.
  1346.     Top        = x coordinate of top left hand corner to start conversion.
  1347.     Left         = y coordinate of top left hand corner to start conversion.
  1348.     Width         = Width in pixels of region to cut.
  1349.     Height         = Number of lines to cut.
  1350.  
  1351.     RESULT
  1352.  
  1353.  
  1354.     CONSIDERATIONS
  1355.     The destination planes must be on a word boundary.
  1356.  
  1357.     SEE ALSO
  1358.     RGBtoOV()
  1359.  
  1360. opal.library/PaletteMap24
  1361.  
  1362.     NAME
  1363.     PaletteMap24 -- Enable/Disable palette mapping.
  1364.  
  1365.     SYNOPSIS
  1366.     PaletteMap24 (PaletteMap)
  1367.             D0
  1368.  
  1369.     BOOL PaletteMap;
  1370.  
  1371.     FUNCTION
  1372.     If PaletteMap = TRUE, turn on palette mapping, else turn palette mapping off. This function always 
  1373.     operates on the active display screen.
  1374.  
  1375.     INPUTS
  1376.     PaletteMap = True to turn palette mapping on, to turn it off.
  1377.  
  1378.     RESULT
  1379.     None
  1380.  
  1381.     CONSIDERATIONS
  1382.     This function cannot be used in 15bit mode.
  1383.  
  1384.     SEE ALSO
  1385.     SetPalette24()
  1386.  
  1387. opal.library/ReadPFPixel24
  1388.  
  1389.     NAME
  1390.     ReadPFPixel24 -- Returns the state of a give playfield stencil pixel.
  1391.  
  1392.     SYNOPSIS
  1393.     Result = ReadPFPixel24 (OScrn,  x,  y)
  1394.     D0            A0    D0  D1
  1395.  
  1396.     long Result;
  1397.     struct OpalScreen *OScrn;
  1398.     long x;
  1399.     long y;
  1400.  
  1401.     FUNCTION
  1402.     This function returns 1 if the corresponding playfield stencil pixel is set, or 0 if it is cleared. If the 
  1403.     coordinates are outside of the clip boundary then -1 is returned.
  1404.  
  1405.     INPUTS
  1406.     OScrn     = OpalScreen to be read.
  1407.     x     = x Coordinate of pixel to read.
  1408.     y     = y Coordinate of pixel to read.
  1409.  
  1410.     RESULT
  1411.     Result = 0 if pixel clear , or 1 if pixel set, -1 if pixel is out of range.
  1412.  
  1413.     CONSIDERATIONS
  1414.  
  1415.     SEE ALSO
  1416.     WritePFPixel24()
  1417.     ClearPFStencil24()
  1418.     SetPFStencil24()
  1419.  
  1420. opal.library/ReadPixel24
  1421.  
  1422.     NAME
  1423.     ReadPixel24 -- Returns colour information for a given pixel.
  1424.  
  1425.     SYNOPSIS
  1426.     Error = ReadPixel24 (OScrn,  x,  y)
  1427.     D0             A0         D0  D1
  1428.  
  1429.     long Error;
  1430.     struct OpalScreen *OScrn;
  1431.     long x;
  1432.     long y;
  1433.  
  1434.     FUNCTION
  1435.     Return the colour (bit plane) information for a given pixel. If the OpalScreen is in palette mapped mode, 
  1436.     the actual bit plane data (and not the corresponding palette value) will be returned.
  1437.  
  1438.     The returned value is placed in Red, Green and Blue in the OpalScreen structure while in 24bit modes. In 
  1439.     15bit mode, the colour is returned in Red and Green, while in 8bit mode, the colour is returned in Red. 
  1440.     The GetPen macros can be used to extract the components from the returned value. 
  1441.  
  1442.     Use the macros GetCol24(), GetCol15(), GetCol8() or GetCol8P() for 8 bit palette mapped to return the 
  1443.     pixel value.
  1444.  
  1445.     If the coordinates are outside the screen's clipping region, Error will be -1, else Error = 0.
  1446.  
  1447.     This function can operate on any sized screens in chip or fast ram.
  1448.  
  1449.     INPUTS
  1450.     OScrn     = OpalScreen to be read.
  1451.     x     = x Coordinate of pixel to read.
  1452.     y     = y Coordinate of pixel to read.
  1453.  
  1454.     RESULT
  1455.     Error     = 0 if no error occurred, or -1 if pixel was out of the clipping region.
  1456.  
  1457.     CONSIDERATIONS
  1458.  
  1459.  
  1460.     SEE ALSO
  1461.  
  1462. WritePixel24()
  1463.  
  1464. opal.library/ReadPRPixel24
  1465.  
  1466.     NAME
  1467.     ReadPRPixel24 -- Returns the state of a give priority stencil pixel.
  1468.  
  1469.     SYNOPSIS
  1470.     Result = ReadPRPixel24 (OScrn,  x,  y)
  1471.     D0            A0    D0  D1
  1472.  
  1473.     long Result;
  1474.     struct OpalScreen *OScrn;
  1475.     long x;
  1476.     long y;
  1477.  
  1478.     FUNCTION
  1479.     This function returns 1 if the corresponding priority stencil pixel is set, or 0 if it is cleared. If the 
  1480.     coordinates are outside of the clip boundary then -1 is returned.
  1481.  
  1482.     INPUTS
  1483.     OScrn     = OpalScreen to be read.
  1484.     x     = x Coordinate of pixel to read.
  1485.     y    = y Coordinate of pixel to read.
  1486.  
  1487.     RESULT
  1488.     Result     = 0 if pixel clear , or 1 if pixel set, -1 if pixel is out of range.
  1489.  
  1490.     CONSIDERATIONS
  1491.  
  1492.     SEE ALSO
  1493.  
  1494.     WritePRPixel24()
  1495.     ClearPRStencil24()
  1496.     SetPRStencil24()
  1497.  
  1498. opal.library/RectFill24
  1499.  
  1500.     NAME
  1501.     RectFill24 -- Draws a solid rectangle.
  1502.  
  1503.     SYNOPSIS
  1504.     void RectFill24 (OScrn, Left, Top, Bottom, Right)
  1505.              A0    D0    D1   D2      D3
  1506.  
  1507.     struct OpalScreen *OScrn;
  1508.     long Left;
  1509.     long Top;
  1510.     long Bottom;
  1511.     long Right;
  1512.  
  1513.     FUNCTION
  1514.     Draws a solid rectangle with the colour specified by Pen_R,Pen_G & Pen_B in the OpalScreen structure.
  1515.  
  1516.     The Rectangle is clipped if all or part of it lies outside the clipping region.
  1517.  
  1518.     INPUTS
  1519.     OScrn    = OpalScreen to be rendered into.
  1520.     Left    = x coordinate of top left-hand corner of the rectangle.
  1521.     Top    = y coordinate of top left-hand corner of the rectangle.
  1522.     Bottom    = x coordinate of the bottom right-hand corner of rectangle.
  1523.     Right    = y coordinate of the bottom right-hand corner of rectangle.
  1524.  
  1525.     RESULT
  1526.     None
  1527.  
  1528.     CONSIDERATIONS
  1529.  
  1530.  
  1531.     SEE ALSO
  1532.  
  1533. opal.library/Refresh24
  1534.  
  1535.     NAME
  1536.     Refresh24 -- Refreshes the frame buffer.
  1537.  
  1538.     SYNOPSIS
  1539.     void Refresh24 (void)
  1540.  
  1541.     FUNCTION
  1542.     Initiates DMA of the currently displayed OpalScreen to the framebuffer. This function will update the 
  1543.     framebuffer in the minimum number of frames required, stop DMA (updates) and return.
  1544.  
  1545.     This function should be called after any drawing routine, and other routines such as LoadIFF24 which 
  1546.     modify memory, to make the frame buffer (and hence display) consistent with the image in Amiga 
  1547.     memory.
  1548.  
  1549.     INPUTS
  1550.     None
  1551.  
  1552.     RESULT
  1553.     None
  1554.  
  1555.     CONSIDERATIONS
  1556.  
  1557.  
  1558.     SEE ALSO
  1559.     UpdateDelay24()
  1560.     StopUpdate24()
  1561.     UpdatePFStencil24()
  1562.     UpdateAll24()
  1563.  
  1564. opal.library/RegWait24
  1565.  
  1566.     NAME
  1567.     RegWait24 -- Wait for register update to complete.
  1568.  
  1569.     SYNOPSIS
  1570.     void RegWait24 (void);
  1571.  
  1572.     FUNCTION
  1573.     This function waits for register information to be updated to the OpalVision before returning, or returns 
  1574.     immediately if no updates are pending.
  1575.  
  1576.     This function is important for synchronizing your program with the OpalVision's update scheme. After 
  1577.     any direct modification of OpalVision registers or after a call to a library function which modifies 
  1578.     registers, this function should be called to allow the update to occur, If this function is not called register 
  1579.     data may be lost.
  1580.  
  1581.     INPUTS
  1582.     None
  1583.  
  1584.     RESULT
  1585.     None
  1586.  
  1587.     CONSIDERATIONS
  1588.  
  1589.  
  1590.     SEE ALSO
  1591.  
  1592. opal.library/RGBtoOV
  1593.  
  1594.     NAME
  1595.     RGBtoOV -- Converts three planes of RGB to OpalVision bitplane data.
  1596.  
  1597.     SYNOPSIS
  1598.     void RGBtoOV (OScrn, RGBPlanes[], Top, Left, Width, Height)
  1599.               A0     A1           D0   D1    D2     D3
  1600.  
  1601.     struct OpalScreen *OScrn;
  1602.     UBYTE **RGBPlanes[];
  1603.     long Top;
  1604.     long Left;
  1605.     long Width;
  1606.     long Height;
  1607.  
  1608.     FUNCTION
  1609.     This call converts three source planes, one containing Red, one Blue and the last Green into OpalVision 
  1610.     bitplane format. This function is useful for pasting clipped regions (using OVtoRGB) back into 
  1611.     OpalVision memory, or for pasting back data after scaling.
  1612.  
  1613.     Unlike the other conversion routines, this function is clipped if it is outside of the clipping region, this 
  1614.     enables it to be used as a drawing function rather than a conversion function.
  1615.  
  1616.     The OpalScreen can be any size, and reside in fast or chip ram.
  1617.  
  1618.     INPUTS
  1619.     OScrn        = OpalScreen structure containing destination bitplanes.
  1620.     RGBPlanes    = Pointer to an array of 3 plane pointers.
  1621.     Top        = x coordinate of top left hand corner to start conversion.
  1622.     Left        = y coordinate of top left hand corner to start conversion.
  1623.     Width        = Width in pixels of region to cut.
  1624.     Height        = Number of lines to cut.
  1625.  
  1626.     RESULT
  1627.     None
  1628.  
  1629.     CONSIDERATIONS
  1630.  
  1631.  
  1632.     SEE ALSO
  1633.     OVtoRGB()
  1634.  
  1635. opal.library/SaveIFF24
  1636.  
  1637.     NAME
  1638.     SaveIFF24 -- Save an OpalScreen as an IFF file.
  1639.  
  1640.     SYNOPSIS
  1641.     Error = SaveIFF24 (OScrn, FileName, ChunkFunction, Flags)
  1642.     D0                 A0     A1        A2             D0
  1643.  
  1644.     long Error;
  1645.     struct OpalScreen *OScrn;
  1646.     char *FileName;
  1647.     long (*ChunkFunction)();
  1648.     long Flags;
  1649.  
  1650.     FUNCTION
  1651.  
  1652.     SaveIFF24 will save any sized OpalScreen in normal IFF file format. The chunks written will include
  1653.  
  1654.         CAMG    - Containing the resolution  (Hires/Interlace/Overscan)
  1655.         CMAP    - Colour map if in 8bit mode.
  1656.         CLUT    - Colour lookup tables if in true colour mode.
  1657.         OVTN    - OpalVision 24bit thumb-nail for display in OpalPaint,
  1658.               OpalShow and other system software.
  1659.         BODY    - Standard 24 bit ILBM data using byte run encoding.
  1660.  
  1661.     If ChunkFunction is not NULL, the function that it points at will be called after the file has been opened 
  1662.     (and FORM ILBM has been written) and before any other chunks have been written. ChunkFunction is 
  1663.     used to insert your own chunks into the IFF file before any of the above chunks. The DOS File Handle for 
  1664.     the open file will be passed to the function on the stack (in standard C calling convention) the chunk 
  1665.     function must return 0 or an error code.
  1666.  
  1667.     Flags:
  1668.         OVFASTFORMAT     - Save as OpalVision fast format.
  1669.         NOTHUMBNAIL    - Inhibit writing thumb-nail chunk.
  1670.         SAVEMASK24        - Saves mask plane if one exists.
  1671.  
  1672.     INPUTS
  1673.     OScrn        = OpalScreen to be saved.
  1674.     FileName    = Filename of file to be written (including full path).
  1675.     ChunkFunction    = Pointer to code to be executed after file is opened.
  1676.  
  1677.     RESULT
  1678.     Error    = 0 if no error code, >0 if error occurred.
  1679.  
  1680.     CONSIDERATIONS
  1681.  
  1682.     SEE ALSO
  1683.  
  1684.     LoadImage24()
  1685.     SaveJPEG24()
  1686.  
  1687. opal.library/SaveJPEG24
  1688.  
  1689.     NAME
  1690.     SaveJPEG24 -- Save an OpalScreen as a JPEG JFIF file.
  1691.  
  1692.     SYNOPSIS
  1693.     Error = SaveJPEG24 (OScrn, FileName, Flags, Quality)
  1694.     D0            A0       A1         D0     D1
  1695.  
  1696.     long Error;
  1697.     struct OpalScreen *OScrn;
  1698.     char *FileName;
  1699.     long Flags;
  1700.     long Quality;
  1701.  
  1702.     FUNCTION
  1703.     SaveJPEG24 will save any sized OpalScreen in the JPEG JFIF file format. JPEG is a compression 
  1704.     standard which enables a large amount of compression to be gained on continuous tone images with 
  1705.     minimum loss in image quality. It should be stressed that this compression method is based on 
  1706.     continuous tone images and compression of images with sharp edges may suffer more degradation. For 
  1707.     more details see the JPEG draft  standard ISO/IEC Dis10918-1. 
  1708.  
  1709.     This generates a base line JPEG file using interleaved components, Huffman entropy compression and 8 
  1710.     bit quatization tables. A thumbnail will also be written into the APP0 marker of the JFIF file unless the 
  1711.     NOTHUMBNAIL flag is set.
  1712.  
  1713.     The quality factor is a percentage value (0...100) which defines the allowable amount of loss in the 
  1714.     compressed image. A factor of 100 corresponds to a quantization table of all 1's and hence has no 
  1715.     quantization loss. A value of 50 corresponds to the quantization tables suggested by the draft standard as 
  1716.     being acceptable for good image quality. A reasonable default value to use is 75, using this level for 
  1717.     continuous tone scanned images a compression factor of  between 15:1 and 20:1 is typical. 
  1718.  
  1719.     Flags:
  1720.         NOTHUMBNAIL    - Inhibit writing thumb-nail chunk.
  1721.  
  1722.     INPUTS
  1723.     OScrn    = OpalScreen to be saved.
  1724.     FileName= Filename of file to be written (including full path).
  1725.     Flags    = See above.
  1726.     Quality    = (0...100) This determines the amount of loss allowed in the compression of     
  1727.            the image. 100 % corresponds to minimum loss.
  1728.  
  1729.     RESULT
  1730.     Error        = 0 if no error code, >0 if error occurred.
  1731.  
  1732.     CONSIDERATIONS
  1733.  
  1734.     SEE ALSO
  1735.  
  1736. LoadImage24()
  1737.  
  1738. opal.library/Scroll24
  1739.  
  1740.     NAME
  1741.     Scroll24 -- Scrolls currently displayed OpalVision image.
  1742.  
  1743.     SYNOPSIS
  1744.     void Scroll24 (DeltaX, DeltaY)
  1745.             D0     D1
  1746.  
  1747.     long DeltaX;
  1748.     long DeltaY;
  1749.  
  1750.     FUNCTION
  1751.     This function scrolls the currently displayed image by DeltaX pixels horizontally, and DeltaY lines 
  1752.     vertically, by modifying the video load address register in the OpalVision.
  1753.  
  1754.     DeltaX and DeltaY are signed values, to enable scrolling in all directions.
  1755.  
  1756.     This function also clears the ADDLOAD bit on the first CoPro instruction if it is not already cleared.
  1757.  
  1758.     INPUTS
  1759.     DeltaX    = Number of pixels to scroll horizontally.
  1760.     DeltaY    = Number of lines to scroll vertically.
  1761.  
  1762.     RESULT
  1763.     None
  1764.  
  1765.     CONSIDERATIONS
  1766.     For the Scroll to function correctly, update DMA to the framebuffer must be turned off by calling 
  1767.     StopUpdate24().
  1768.  
  1769.     SEE ALSO
  1770.     SetLoadAddress24()
  1771.  
  1772. opal.library/SetControlBit24
  1773.  
  1774.     NAME
  1775.     SetControlBit24 -- Modifies a bit in the control line register.
  1776.  
  1777.     SYNOPSIS
  1778.     void SetControlBit24 (FrameNumber, BitNumber, State)
  1779.                   D0       D1          D2
  1780.  
  1781.     long FrameNumber;
  1782.     long BitNumber;
  1783.     BOOL State;
  1784.  
  1785.     FUNCTION
  1786.     Sets or clears a bit in the control line register. See "The Opal Control Line Register" for details.
  1787.  
  1788.     There are 14 different versions of the control line register used to update the maximum of 12 different 
  1789.     memory segments. These differ by the state of the bank and field write enable bits. The frame number 
  1790.     variable specifies which one of these registers should be updated, for bits such as AUTO or COL/CoPro a 
  1791.     global change may be required (i.e. changing all 12 control lines). 
  1792.  
  1793.         Frame Number        Description
  1794.              0        Red Bank0, Field0 Update
  1795.              1        Green Bank0, Field0 Update
  1796.              2        Blue Bank0, Field0 Update
  1797.              3        Red Bank0, Field1 Update
  1798.              4        Green Bank0, Field1 Update
  1799.              5        Blue Bank0, Field1 Update
  1800.              6        Red Bank1, Field0 Update
  1801.              7        Green Bank1, Field0 Update
  1802.              8        Blue Bank1, Field0 Update
  1803.              9        Red Bank1, Field1 Update
  1804.              10        Green Bank1, Field1 Update
  1805.              11        Blue Bank1, Field1 Update
  1806.              12        Field 0 Display only
  1807.              13        Field 1 Display only
  1808.  
  1809.  
  1810.     INPUTS
  1811.     FrameNumber    = The OpalVision update frame number to modify. One frame corresponds to 
  1812.             one bank update (maximum 12 frames, 2 noupdate lists).
  1813.     BitNumber    = Bit number within control line to modify (4...19).
  1814.     State         = State to be written into bit (Boolean).
  1815.  
  1816.     RESULT
  1817.     None
  1818.  
  1819.     CONSIDERATIONS
  1820.     These bits should be modified with caution. 
  1821.  
  1822.     SEE ALSO
  1823.     Control Line Register
  1824.  
  1825. opal.library/SetCoPro24
  1826.  
  1827.     NAME
  1828.     SetCoPro24 -- Modifies a single instruction in the CoPro list. 
  1829.  
  1830.     SYNOPSIS
  1831.     void SetCoPro24 (InstructionNumber, Instruction);
  1832.              D0            D1  
  1833.  
  1834.     long InstructionNumber;
  1835.     long Instruction;
  1836.  
  1837.     FUNCTION
  1838.     This function modifies a single CoPro instruction and initiates an update to the OpalVision CoPro. Note 
  1839.     that this function is much faster than calling UpdateCoPro24().
  1840.  
  1841.     INPUTS
  1842.     InstructionNumber    = The CoPro instruction number (0...289)
  1843.     Instruction        = 8Bit CoPro instruction. See "The CoPro"
  1844.  
  1845.     RESULT
  1846.     None
  1847.  
  1848.     CONSIDERATIONS
  1849.     InstructionNumber should be less than LastCoProIns in the OpalScreen structure.
  1850.  
  1851.     SEE ALSO
  1852.     UpdateCoPro24()
  1853.  
  1854. opal.library/SetDisplayBottom24
  1855.  
  1856.     NAME
  1857.     SetDisplayBottom24 -- Sets the lower limit of the OpalVision screen. 
  1858.  
  1859.     SYNOPSIS
  1860.     Result = SetDisplayBottom24 (BottomLine);
  1861.                     D0
  1862.  
  1863.     long BottomLine;
  1864.     BOOL Result;
  1865.  
  1866.     FUNCTION
  1867.     This function specifies the lower limit of the OpalVision screen. Below this point Amiga only graphics 
  1868.     will be displayed. Once a display bottom has been set, the region below that line will always contains 
  1869.     Amiga graphics regardless of whether the frame buffer is being updated or not. This is useful for 
  1870.     displaying Amiga gadgets on the screen.
  1871.  
  1872.     INPUTS
  1873.     BottomLine    -Specifies the last line of OpalVision graphics.
  1874.  
  1875.     RESULT
  1876.     Result         = 1 if operation successful, 0 if operation failed.
  1877.  
  1878.     CONSIDERATIONS
  1879.     This function uses the CoPro to enable Amiga graphics on the bottom section of the screen. To ensure 
  1880.     that the display is not corrupted, only CoPro instructions up to the line specified by LastCoProIns in the 
  1881.     OpalScreen structure should be modified.
  1882.  
  1883.     SEE ALSO
  1884.     ClearDisplayBottom24 ()
  1885.  
  1886. opal.library/SetHires24
  1887.  
  1888.     NAME
  1889.     SetHires24 -- Enable a hires display for a section of the screen. 
  1890.  
  1891.     SYNOPSIS
  1892.     Result = SetHires24 (TopLine, Lines);
  1893.                  D0       D1
  1894.     long TopLine;
  1895.     long Lines;
  1896.  
  1897.     FUNCTION
  1898.     Sets the HIRESDISP bits on CoPro instructions starting at TopLine for 'Lines' number of lines. Both 
  1899.     TopLine and Lines must be specified as a non-interlaced scan line (i.e. must be divided by 2 if an 
  1900.     interlaced screen).
  1901.  
  1902.     INPUTS
  1903.     TopLine        -Specifies the first line to start setting HIRESDISP bits.
  1904.     Lines        -Number of lines to modify.
  1905.  
  1906.     RESULT
  1907.     None
  1908.  
  1909.     CONSIDERATIONS
  1910.  
  1911.     SEE ALSO
  1912.     SetLores24 ()
  1913.  
  1914. opal.library/SetLoadAddress24
  1915.  
  1916.     NAME
  1917.     SetLoadAddress24 -- Updates the OpalVision load address register.
  1918.  
  1919.     SYNOPSIS
  1920.     void SetLoadAddress24 (void)
  1921.  
  1922.     FUNCTION
  1923.     This function uses the Load Address value in the displayed OpalScreen structure to update the load 
  1924.     address register in the OpalVision.
  1925.  
  1926.     This function is useful for scrolling and distortion effects. 
  1927.  
  1928.     The modulo for a scan line is given in the OpalScreen structure and is independent of the display 
  1929.     resolution.
  1930.  
  1931.     INPUTS
  1932.     None
  1933.  
  1934.     RESULT
  1935.     None
  1936.  
  1937.     CONSIDERATIONS
  1938.     Load Address only has an effect when a CoPro instruction having its ADDLOAD bit cleared is executed. 
  1939.     Therefore a combination of CoPro instructions and the address load register are required to produce the 
  1940.     effect.
  1941.  
  1942.     SEE ALSO
  1943.     Scroll24()
  1944.  
  1945. opal.library/SetLores24
  1946.  
  1947.     NAME
  1948.     SetLores24 -- Enable a Lores display for a section of the screen. 
  1949.  
  1950.     SYNOPSIS
  1951.     Result = SetLores24 (TopLine, Lines);
  1952.                  D0       D1
  1953.     long TopLine;
  1954.     long Lines;
  1955.  
  1956.     FUNCTION
  1957.     Clears the HIRESDISP bits on CoPro instructions starting at TopLine for 'Lines' number of lines. Both 
  1958.     TopLine and Lines must be specified as a non-interlaced scan line (i.e. must be divided by 2 if an 
  1959.     interlaced screen).
  1960.  
  1961.     INPUTS
  1962.     TopLine        -Specifies the first line to start clearing HIRESDISP bits.
  1963.     Lines        -Number of lines to modify.
  1964.  
  1965.     RESULT
  1966.     None
  1967.  
  1968.     CONSIDERATIONS
  1969.  
  1970.     SEE ALSO
  1971.     SetHires24 ()
  1972.  
  1973. opal.library/SetPFStencil24
  1974.  
  1975.     NAME
  1976.     SetPFStencil24 -- Sets the PlayField Stencil of the specified Screen.
  1977.  
  1978.     SYNOPSIS
  1979.     void SetPFStencil24 (OScrn);
  1980.                  A0
  1981.  
  1982.     struct OpalScreen *OScrn;
  1983.  
  1984.     FUNCTION
  1985.     Sets the playfield stencil (least significant bit of green bank 0) of all of the pixels in the specified screen.
  1986.  
  1987.     INPUTS
  1988.     OScrn    = OpalScreen structure.
  1989.  
  1990.     RESULT
  1991.     None
  1992.  
  1993.     CONSIDERATIONS
  1994.     This will only have an effect if Dual Playfield mode has been set up using DualPlayField24().
  1995.  
  1996.     SEE ALSO
  1997.     ClearPFStencil()
  1998.     DualPlayField24()
  1999.     SinglePlayField24()
  2000.  
  2001. opal.library/SetPRStencil24
  2002.  
  2003.     NAME
  2004.     SetPRStencil24 -- Sets the Priority Stencil of the specified Screen.
  2005.  
  2006.     SYNOPSIS
  2007.     void SetPRStencil24 (OScrn);
  2008.                  A0
  2009.  
  2010.     struct OpalScreen *OScrn;
  2011.  
  2012.     FUNCTION
  2013.     Sets the priority stencil (least significant bit of blue bank 0) of all pixels in the specified screen.
  2014.  
  2015.     INPUTS
  2016.     OScrn    = OpalScreen structure.
  2017.  
  2018.     RESULT
  2019.     None
  2020.  
  2021.     CONSIDERATIONS
  2022.     This will only have an effect if dual OpalVision/Amiga display mode has been set up using 
  2023.     DualDisplay24().
  2024.  
  2025.     SEE ALSO
  2026.     ClearPRStencil()
  2027.     DualDisplay24()
  2028.     SingleDisplay24()
  2029.  
  2030. opal.library/SetRGB24
  2031.  
  2032.     NAME
  2033.     SetRGB24 -- Updates a single palette entry to the OpalVision palette registers.
  2034.  
  2035.     SYNOPSIS
  2036.     void SetRGB24 (Entry, Red,  Green,  Blue);
  2037.             D0    D1    D2      D3
  2038.  
  2039.     long Entry;
  2040.     long Red;
  2041.     long Green;
  2042.     long Blue;
  2043.  
  2044.     FUNCTION
  2045.     This function updates a single palette entry in the OpalVision palette registers.
  2046.  
  2047.     INPUTS
  2048.     Entry    - The entry selected for update (0-255).
  2049.     Red    - Red value (0-255).
  2050.     Green    - Green value (0-255).
  2051.     Blue    - Blue value (0-255).
  2052.  
  2053.     RESULT
  2054.     None
  2055.  
  2056.     CONSIDERATIONS
  2057.     This function will only have a visible effect when in palette mapped mode.
  2058.  
  2059.     SEE ALSO
  2060.     PaletteMap ()
  2061.     SetPalette ()
  2062.  
  2063. opal.library/SetScreen24
  2064.  
  2065.     NAME
  2066.     SetScreen24 -- Fills screen with a specified colour.
  2067.  
  2068.     SYNOPSIS
  2069.     void SetScreen24 (OScrn)
  2070.                 A0
  2071.  
  2072.     struct OpalScreen *OScrn;
  2073.  
  2074.     FUNCTION
  2075.     This function is similar to ClearScreen24, but fills the screen with the colour contained in Pen_R,Pen_G 
  2076.     & Pen_B in the OpalScreen structure.
  2077.  
  2078.     INPUTS
  2079.     None
  2080.  
  2081.     RESULT
  2082.     None
  2083.  
  2084.     CONSIDERATIONS
  2085.  
  2086.  
  2087.     SEE ALSO
  2088.     ClearScreen24()
  2089.  
  2090. opal.library/SetSprite24
  2091.  
  2092.     NAME
  2093.     SetSprite24 -- Allows Amiga sprites to be displayed over OpalVision graphics.
  2094.  
  2095.     SYNOPSIS
  2096.     void SetSprite24 (SpriteData, SpriteNumber);
  2097.               A0          D0
  2098.  
  2099.     USHORT *SpriteData;
  2100.     long SpriteNumber;
  2101.  
  2102.     FUNCTION
  2103.     This function allows Amiga hardware sprites to be displayed in OpalVision graphics.
  2104.  
  2105.     Sprites are displayed during both display and update cycles and due to this the sprite data is written into 
  2106.     the frame buffer memory along with the video data. This may be undesirable in some cases, so the sprite 
  2107.     may be removed before starting updates using Refresh24() or UpdateDelay24() by calling SetSprite24() 
  2108.     with SpriteData = NULL
  2109.  
  2110.     SpriteData  is a pointer to a data definition of a spite as passed to the SetPointer() function in the 
  2111.     intuition library. The SpriteNumber is the hardware sprite number to be used to display the sprite, this 
  2112.     will normally be 0 to modify the mouse pointer sprite.
  2113.  
  2114.     N.B.     Passing -1 for the SpriteData will use the currently active Amiga Sprite in the system. For 
  2115.     example SetSprite24((USHORT *) - 1,0) will allow the currently active mouse pointer to be displayed 
  2116.     over the 24 bit image.
  2117.  
  2118.     INPUTS
  2119.     SpriteData    - pointer to the sprite data.
  2120.     SpriteNumber    - Amiga hardware sprite number (0...7).
  2121.  
  2122.     RESULT
  2123.     None
  2124.  
  2125.     CONSIDERATIONS
  2126.     All sprites other than the mouse pointer sprite should be allocated by the user using GetSprite () as sprite 
  2127.     0 is normally used for the mouse pointer and another sprite is required by the opal library for normal 
  2128.     screen updates. 
  2129.  
  2130.     Sprites will only be visible during display cycles if Amiga priority is set and dual display mode is active.
  2131.  
  2132.     SEE ALSO
  2133.  
  2134. opal.library/SingleDisplay24
  2135.  
  2136.     NAME
  2137.     SingleDisplay24 -- Sets up an Amiga/OpalVision single display.
  2138.  
  2139.     SYNOPSIS
  2140.     void SingleDisplay24 (void);
  2141.  
  2142.     FUNCTION
  2143.     This function sets the DUALDISPLAY bit of all CoPro instructions, allowing an OpalVision or Amiga 
  2144.     only display.
  2145.  
  2146.     INPUTS
  2147.     None
  2148.  
  2149.     RESULT
  2150.     None
  2151.  
  2152.     CONSIDERATIONS
  2153.     If Amiga display bottom has been set, using the SetDisplayBottom24() the CoPro instructions will not be 
  2154.     modified for that region of the display.
  2155.  
  2156.     SEE ALSO
  2157.     DualDisplay24()
  2158.  
  2159. opal.library/SinglePlayField24
  2160.  
  2161.     NAME
  2162.     SinglePlayField24() -- Sets up an Amiga or OpalVision single playfield.
  2163.  
  2164.     SYNOPSIS
  2165.     void SinglePlayField24 (void)
  2166.  
  2167.     FUNCTION
  2168.     This function clears the DUALPLAYFIELD bit of all coprocessor instructions, Allowing only one of 
  2169.     OpalVision playfield to be displayed.
  2170.  
  2171.     INPUTS
  2172.     None
  2173.  
  2174.     RESULT
  2175.     None
  2176.  
  2177.     CONSIDERATIONS
  2178.     If an Amiga display bottom has been set, the coprocessor instructions will not be modified for that region 
  2179.     of the display.
  2180.  
  2181.     SEE ALSO
  2182.     DualPlayField24()
  2183.  
  2184. opal.library/StopUpdate24
  2185.  
  2186.     NAME
  2187.     StopUpdate24 -- Stops updates to the frame buffer memory.
  2188.  
  2189.     SYNOPSIS
  2190.     void StopUpdate24 (void);
  2191.  
  2192.     FUNCTION
  2193.     This function stops updates to the OpalVision frame buffer memory initiated with a call to 
  2194.     UpdateDelay24(). This allows changes to be made to the Amiga memory without affecting the 
  2195.     OpalVision frame buffer memory thus offering inherent double buffering. Stopping updates will also 
  2196.     reduce the DMA load on the Amiga.
  2197.  
  2198.     INPUTS
  2199.     None
  2200.  
  2201.     RESULT
  2202.     None
  2203.  
  2204.     CONSIDERATIONS
  2205.     This function may take up to 1 frame as it must wait for the current frame update to be completed.
  2206.  
  2207.     SEE ALSO
  2208.     UpdateDelay24()
  2209.     Refresh24()
  2210.  
  2211. opal.library/UpdateAll24
  2212.  
  2213.     NAME
  2214.     UpdateAll24 -- Resets the internal update structure so all required banks are updated.
  2215.  
  2216.     SYNOPSIS
  2217.     void UpdateAll24 (void);
  2218.  
  2219.     FUNCTION
  2220.     Resets the internal update structure so that all required banks are updated.  This function is useful after a 
  2221.     call to UpdatePFStencil24() to reinitialise the internal state of the library so that all the required segments 
  2222.     are updated correctly on subsequent calls to Refresh24() or UpdateDelay24().
  2223.  
  2224.     INPUTS
  2225.     None
  2226.  
  2227.     RESULT
  2228.     None
  2229.  
  2230.     CONSIDERATIONS
  2231.  
  2232.  
  2233.     SEE ALSO
  2234.     UpdatePFStencil24()
  2235.  
  2236. opal.library/UpdateCoPro24
  2237.  
  2238.     NAME
  2239.     UpdateCoPro24() -- Writes CoPro list for the current display screen to Video coprocessor
  2240.  
  2241.     SYNOPSIS
  2242.     void UpdateCoPro24 (void); 
  2243.  
  2244.     FUNCTION
  2245.     Encodes the entire CoPro instruction list from the displayed screen structure and initiates a coprocessor 
  2246.     update.
  2247.  
  2248.     This function also updates the Load Address Register.
  2249.  
  2250.     INPUTS
  2251.     None
  2252.  
  2253.     RESULT
  2254.     None
  2255.  
  2256.     CONSIDERATIONS
  2257.     Modifying the coprocessor list in the screen structure does not have any effect on the display until 
  2258.     UpdateCoPro24 () is called. 
  2259.  
  2260.     The CoPro list will not be updated in the OpalVision until the next vertical blanking period.
  2261.  
  2262.     SEE ALSO
  2263.     SetCoPro24()
  2264.     RegWait24()
  2265.  
  2266. opal.library/UpdateDelay24
  2267.  
  2268.     NAME
  2269.     UpdateDelay24 () -- Sets the delay between consecutive frame buffer updates.
  2270.  
  2271.     SYNOPSIS
  2272.     void UpdateDelay24 (FrameDelay);
  2273.                 D0
  2274.  
  2275.     long FrameDelay;
  2276.  
  2277.     FUNCTION
  2278.     This function allows a variable frame delay between consecutive frame buffer updates. Setting a frame 
  2279.     delay of zero enables continuous full speed updates.
  2280.  
  2281.     This function also initiates continuous updates to the OpalVision frame buffer memory which will 
  2282.     continue until either Refresh24() or StopUpdate24() is called.
  2283.  
  2284.     Setting a delay increases free bus DMA bandwidth to increase performance of the CPU and other DMA 
  2285.     devices.
  2286.  
  2287.     INPUTS
  2288.     FrameDelay    = Number of Frames to pause between frame buffer updates.
  2289.  
  2290.     RESULT
  2291.     None
  2292.  
  2293.     CONSIDERATIONS
  2294.     UpdateAll24() and UpdatePFStencil24() determine which memory segments will be updated during an 
  2295.     update sequence.
  2296.  
  2297.     SEE ALSO
  2298.     StopUpdate24()
  2299.     UpdateAll24()
  2300.     UpdatePFStencil24()
  2301.     Refresh24()
  2302.  
  2303. opal.library/UpdatePalette24
  2304.  
  2305.     NAME
  2306.     UpdatePalette 24 -- Loads all 256 entries of Red, Green and Blue values in the OpalScreen structure onto 
  2307.             the OpalVision  palette registers.
  2308.  
  2309.     SYNOPSIS
  2310.     void UpdatePalette (void);
  2311.  
  2312.     FUNCTION
  2313.     Updates the OpalVision palette registers with the palette values in the OpalScreen structure.
  2314.  
  2315.     This also updates the Pixel Read mask and the Command Register and uses the Palette Load Address as 
  2316.     an offset for the palette update.
  2317.  
  2318.     INPUTS
  2319.     None
  2320.  
  2321.     RESULT
  2322.     None
  2323.  
  2324.     CONSIDERATIONS
  2325.     Updates will have no effect in non palette mapped modes.
  2326.  
  2327.     SEE ALSO
  2328.     SetRGB24 ()
  2329.     PaletteMap24 ()
  2330.  
  2331. opal.library/UpdatePFStencil24
  2332.  
  2333.     NAME
  2334.     UpdatePFStencil24() -- Updates playfield stencil at highest possible rate.
  2335.  
  2336.     SYNOPSIS
  2337.     void UpdatePFStencil24(void);
  2338.  
  2339.     FUNCTION
  2340.     Enables updates to only the segments containing the playfield stencil (green segments). The speed of 
  2341.     update is three times that of a normal 24bit update. This enables quick playfield transitions.
  2342.  
  2343.     This function does not update the playfield stencil as such, but modifies the internal state of the library so 
  2344.     that subsequent calls to Refresh24() or UpdateDelay24() will only update the segments containing the 
  2345.     playfield stencil. The internal state of the library can be returned to normal by calling UpdateAll24().
  2346.  
  2347.     To use the playfield stencil in 8bit mode, the green bank contains the stencil and therefore must be 
  2348.     updated. The most convenient way to do this is to write the frame for the first playfield in the red 
  2349.     segment of bank 0 using WriteFrame24(0) and the second playfield into the red segment of bank 1 using 
  2350.     WriteFrame24(3). UpdatePFStencil24() will call WriteFrame24(1) when in 8bit mode to switch to the 
  2351.     green segment. Placing you playfields in segments other than the green segment will give you the full 
  2352.     256 colours rather than 128.
  2353.  
  2354.     INPUTS
  2355.     None
  2356.  
  2357.     RESULT
  2358.     None
  2359.  
  2360.     CONSIDERATIONS
  2361.  
  2362.  
  2363.     SEE ALSO
  2364.     UpdateDelay24 ()
  2365.     DualPlayField24()
  2366.     SinglePlayField24()
  2367.     Refresh24()
  2368.     UpdateAll24()
  2369.  
  2370. opal.library/UpdateRegs24()
  2371.  
  2372.     NAME
  2373.     UpdateRegs24 () -- Updates the hardware registers for the current display screen
  2374.  
  2375.     SYNOPSIS
  2376.     void UpdateRegs24 (void)
  2377.  
  2378.     FUNCTION
  2379.     Updates the Pixel Read mask, Command register and Palette Load Address registers in the OpalVision 
  2380.     with the values from the current display screen structure (See "Registers").
  2381.  
  2382.     INPUTS
  2383.     None
  2384.  
  2385.     RESULT
  2386.     None
  2387.  
  2388.     CONSIDERATIONS
  2389.     Changing register values in the screen structure does not take effect until an update has been initiated. 
  2390.  
  2391.     Register updates are not completed until the next vertical blanking period.
  2392.  
  2393.     SEE ALSO
  2394.     RegWait24()
  2395.  
  2396. opal.library/WriteFrame24
  2397.  
  2398.     NAME
  2399.     WriteFrame24 -- Sets the current frame to be written to within the frame buffer memory.
  2400.  
  2401.     SYNOPSIS
  2402.     void WriteFrame24 (Frame);
  2403.                D0
  2404.  
  2405.     long Frame;
  2406.  
  2407.     FUNCTION
  2408.     Depending on the resolution of the displayed OpalVision screen, a number of screens can be stored in the 
  2409.     frame buffer memory. The number of frames available for the screens resolution are given in the 
  2410.     MaxFrames variable in the OpalScreen structure.
  2411.  
  2412.     WriteFrame24() allows each individual frame to be written separately where Frame is in the range 
  2413.     0...MaxFrames. Using a combination of WriteFrame24 and DisplayFrame24, it is possible to store 
  2414.     several images in frame buffer memory and to perform simple page flip animation.  
  2415.  
  2416.     INPUTS
  2417.     Frame    = Frame number to display (0...MaxFrames).
  2418.  
  2419.     RESULT
  2420.     None
  2421.  
  2422.     CONSIDERATIONS
  2423.     The display frame and the write frame, must reside in the same field area in the frame buffer memory. 
  2424.     (See "Memory Segment Diagram"). Due to this WriteFrame24() has the side effect of changing the 
  2425.     display frame if the new write frame is in a different field. 
  2426.  
  2427.     SEE ALSO
  2428.     DisplayFrame24()
  2429.  
  2430. opal.library/WritePFPixel24
  2431.  
  2432.     NAME
  2433.     WritePFPixel24 () -- Set or clear a pixel in the playfield stencil.
  2434.  
  2435.     SYNOPSIS
  2436.     Result = WritePFPixel24 (OScrn, x, y);
  2437.     D0             A0     D0 D1    
  2438.  
  2439.     struct OpalScreen *OScrn;
  2440.     long x;
  2441.     long y;
  2442.     long Result;
  2443.  
  2444.     FUNCTION
  2445.     Sets or clears a pixel in the playfield stencil depending on the state of Pen_R in the screen structure. If 
  2446.     Pen_R is = 0, the pixel will be cleared else it is set. The SetPFPen macro can be used to initialize Pen_R.  
  2447.  
  2448.     INPUTS
  2449.     OScrn    = A pointer to an OpalScreen structure.
  2450.     x    = x coordinate of pixel. 
  2451.     y    = y coordinate of pixel. 
  2452.  
  2453.     RESULT
  2454.     Result    = -1 if the pixel is outside the clip boundary else 0.
  2455.  
  2456.     CONSIDERATIONS
  2457.     This function only has visible effect in dual playfield mode.
  2458.  
  2459.     SEE ALSO
  2460.     ReadPFPixel24()
  2461.     UpdatePFStencil()
  2462.     DualPlayField24()
  2463.     SinglePlayfield24()
  2464.  
  2465. opal.library/WritePixel24
  2466.  
  2467.     NAME
  2468.     WritePixel24 () -- Write a pixel into an OpalScreen.
  2469.  
  2470.     SYNOPSIS
  2471.     Result = WritePixel24 (OScrn, x, y);
  2472.     D0                   A0     D0 D1        
  2473.  
  2474.  
  2475.     struct OpalScreen *OScrn;
  2476.     long x;
  2477.     long y;
  2478.     long Result;
  2479.  
  2480.     FUNCTION
  2481.     Writes a pixel in the specified OpalScreen using the current pen value in that structure. The macro 
  2482.     SetPen can be used to initialize pen values correctly.
  2483.  
  2484.     INPUTS
  2485.     OScrn    = A pointer to an OpalScreen structure.
  2486.     x    = x coordinate of pixel. 
  2487.     y    = y coordinate of pixel. 
  2488.  
  2489.     RESULT
  2490.     Result    = -1 if the pixel is outside the clip boundary else 0.
  2491.  
  2492.     CONSIDERATIONS
  2493.  
  2494.  
  2495.     SEE ALSO
  2496.     ReadPixel24()
  2497.  
  2498. opal.library/WritePRPixel24
  2499.  
  2500.     NAME
  2501.     WritePRPixel24 () -- Set or clear a pixel in the priority stencil.
  2502.  
  2503.     SYNOPSIS
  2504.     Result = WritePRPixel24 (OScrn, x, y);
  2505.     D0                 A0     D0 D1        
  2506.  
  2507.     struct OpalScreen *OScrn;
  2508.     long x;
  2509.     long y;
  2510.     long Result;
  2511.  
  2512.     FUNCTION
  2513.     Sets or clears a pixel in the priority stencil depending on the state of Pen_R in the screen structure. If 
  2514.     Pen_R is = 0, the pixel will be cleared else it is set. The macro SetPRPen can be used to initialize the 
  2515.     state of Pen_R. 
  2516.  
  2517.     INPUTS
  2518.     OScrn    = A pointer to an OpalScreen structure.
  2519.     x    = x coordinate of pixel. 
  2520.     y    = y coordinate of pixel. 
  2521.  
  2522.     RESULT
  2523.     Result    = -1 if the pixel is outside the clip boundary else 0.
  2524.  
  2525.     CONSIDERATIONS
  2526.     This function only has visible effect when the priority stencil is enabled.
  2527.  
  2528.     SEE ALSO
  2529.     ReadPRPixel24()
  2530.     EnablePRStencil24()
  2531.     DisablePRStencil24()
  2532.  
  2533. opal.library/WriteThumbnail24
  2534.  
  2535.     NAME
  2536.     WriteThumbnail24 -- Writes an IFF thumb-nail chunk into a file.
  2537.  
  2538.     SYNOPSIS
  2539.     ReturnCode = WriteThumbnail24 (OScrn, File);
  2540.     D0                A0    A1
  2541.  
  2542.     struct OpalScreen *OScrn;
  2543.     BPTR File;
  2544.     long ReturnCode;
  2545.  
  2546.  
  2547.     FUNCTION
  2548.     This function generates a 24 bit thumb-nail for the given OpalScreen and writes an IFF OVTN thumb-
  2549.     nail chunk into the given file.
  2550.  
  2551.     INPUTS
  2552.     OScrn    = OpalScreen to generate the thumb-nail for.
  2553.     File    = File Handle of the file to write thumb-nail to.
  2554.  
  2555.     RESULT
  2556.     ReturnCode = 0 if all ok, or an OpalVision Error code  if en error occurred.
  2557.  
  2558.     CONSIDERATIONS
  2559.  
  2560.  
  2561.     SEE ALSO
  2562.     SaveIFF24()
  2563.     LoadIFF24()
  2564.  
  2565.  
  2566. opalreq.library/OpalRequester
  2567.  
  2568.     NAME
  2569.     OpalRequester -- The OpalVision file requester.
  2570.  
  2571.     SYNOPSIS
  2572.     ReturnCode = OpalRequester (OReq);
  2573.     D0                A0
  2574.  
  2575.     struct OpalReq *OReq;
  2576.  
  2577.     FUNCTION
  2578.     This is the entry point for the OpalVision requester. OReq is a pointer to a properly initialised OpalReq 
  2579.     structure defined in the above sections. The requester will be displayed and handled completely by the 
  2580.     library, when the user has selected a file or hit cancel, this function will return the selected file and 
  2581.     directory name in OReq. OKHit will be cleared if the user hit the Cancel gadget and set otherwise.
  2582.  
  2583.     INPUTS
  2584.     OReq    = A pointer to a correctly initialised OpalReq structure.
  2585.  
  2586.     RESULT
  2587.     ReturnCode = 0 if all ok
  2588.            =  OR_ERR_OUTOFMEM if there is not enough memory to display requester
  2589.            =  OR_ERR_INUSE if the requester is currently in use.
  2590.  
  2591.     CONSIDERATIONS
  2592.     For this release the intuition screen used to display the requester
  2593.     must be hires interlaced, and have atleast 2 bit planes.
  2594.  
  2595.     SEE ALSO
  2596.  
  2597.